---
title: "Integrate Mastra in your React + Vite project | Frameworks"
description: A step-by-step guide to integrating Mastra with React and Vite.
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

# Integrate Mastra in your React + Vite project

Mastra integrates with Vite, making it easy to:

- Build flexible APIs to serve AI-powered features
- Simplify deployment with a unified codebase for frontend and backend
- Take advantage of Mastra's Client SDK

Use this guide to scaffold and integrate Mastra with your React + Vite project.

:::warning

This guide assumes you're using React + Vite with React Router v7 at the root of your project, e.g., `app`.

:::

## Install Mastra

Install the required Mastra packages:

<Tabs>
<TabItem value="npm" label="npm">

```bash copy
npm install mastra@beta @mastra/core@beta @mastra/libsql@beta @mastra/client-js@beta
```

</TabItem>
<TabItem value="yarn" label="yarn">

```bash copy
yarn add mastra@beta @mastra/core@beta @mastra/libsql@beta @mastra/client-js@beta
```

</TabItem>
<TabItem value="pnpm" label="pnpm">

```bash copy
pnpm add mastra@beta @mastra/core@beta @mastra/libsql@beta @mastra/client-js@beta
```

</TabItem>
<TabItem value="bun" label="bun">

```bash copy
bun add mastra@beta @mastra/core@beta @mastra/libsql@beta @mastra/client-js@beta
```

</TabItem>
</Tabs>

## Integrate Mastra

To integrate Mastra into your project, you have two options:

### 1. Use the One-Liner

Run the following command to quickly scaffold the default Weather agent with sensible defaults:

```bash copy
npx mastra@beta init --dir . --components agents,tools --example --llm openai
```

> See [mastra init](/reference/v1/cli/create-mastra) for more information.

### 2. Use the Interactive CLI

If you prefer to customize the setup, run the `init` command and choose from the options when prompted:

```bash copy
npx mastra@latest init
```

:::warning

By default, `mastra init` suggests `src` as the install location. If you're using React + Vite at the root of your project (e.g., `app`, not `src/app`), enter `.` when prompted:

:::

Add the `dev` and `build` scripts to `package.json`:

<Tabs>
<TabItem value="app" label="app">

```json title="package.json"
{
  "scripts": {
    ...
    "dev:mastra": "mastra dev --dir mastra",
    "build:mastra": "mastra build --dir mastra"
  }
}
```

</TabItem>
<TabItem value="src-app" label="src/app">

```json title="package.json"
{
  "scripts": {
    ...
    "dev:mastra": "mastra dev --dir src/mastra",
    "build:mastra": "mastra build --dir src/mastra"
  }
}
```

</TabItem>
</Tabs>

## Configure TypeScript

Modify the `tsconfig.json` file in your project root:

```json title="tsconfig.json"
{
  ...
  "exclude": ["dist", ".mastra"]
}
```

## Set Up API Keys

```bash title=".env" copy
OPENAI_API_KEY=<your-api-key>
```

> Each LLM provider uses a different env var. See [Model Capabilities](https://sdk.vercel.ai/providers) for more information.

## Update .gitignore

Add `.mastra` to your `.gitignore` file:

```bash title=".gitignore" copy
.mastra
```

## Start the Mastra Dev Server

Start the Mastra Dev Server to expose your agents as REST endpoints:

<Tabs>
<TabItem value="npm" label="npm">

```bash copy
npm run dev:mastra
```

</TabItem>
<TabItem value="cli" label="CLI">

```bash copy
mastra dev:mastra
```

</TabItem>
</Tabs>

> Once running, your agents are available locally. See [Local Development Environment](/docs/v1/getting-started/studio) for more information.

## Start Vite Dev Server

With the Mastra Dev Server running, you can start your Vite app in the usual way.

## Create Mastra Client

Create a new directory and file. Then add the example code:

```bash copy
mkdir lib
touch lib/mastra.ts
```

```typescript title="lib/mastra.ts" showLineNumbers copy
import { MastraClient } from "@mastra/client-js";

export const mastraClient = new MastraClient({
  baseUrl: import.meta.env.VITE_MASTRA_API_URL || "http://localhost:4111",
});
```

## Create Test Route Config

Add new `route` to the config:

```typescript title="app/routes.ts" showLineNumbers copy
import { type RouteConfig, index, route } from "@react-router/dev/routes";

export default [
  index("routes/home.tsx"),
  route("test", "routes/test.tsx"),
] satisfies RouteConfig;
```

## Create Test Route

Create a new Route, and add the example code:

```bash copy
touch app/routes/test.tsx
```

```typescript title="app/routes/test.tsx" showLineNumbers copy
import { useState } from "react";
import { mastraClient } from "../../lib/mastra";

export default function Test() {
  const [result, setResult] = useState<string | null>(null);

  async function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();

    const formData = new FormData(event.currentTarget);
    const city = formData.get("city")?.toString();
    const agent = mastraClient.getAgent("weatherAgent");

    const response = await agent.generate({
      messages: [{ role: "user", content: `What's the weather like in ${city}?` }]
    });

    setResult(response.text);
  }

  return (
    <>
      <h1>Test</h1>
      <form onSubmit={handleSubmit}>
        <input name="city" placeholder="Enter city" required />
        <button type="submit">Get Weather</button>
      </form>
      {result && <pre>{result}</pre>}
    </>
  );
}
```

> You can now navigate to `/test` in your browser to try it out.

Submitting **London** as the city would return a result similar to:

```plaintext
The current weather in London is partly cloudy with a temperature of 19.3°C, feeling like 17.4°C. The humidity is at 53%, and there is a wind speed of 15.9 km/h, with gusts up to 38.5 km/h.
```

## Next steps

- [Monorepo Deployment](/docs/v1/deployment/monorepo)
